//===============================================================================
// Microsoft patterns & practices Enterprise Library Contribution
// Query Application Block
//===============================================================================

using System.Collections.Generic;
using System.Data;
using EntLibContrib.Query.Instrumentation;
using Microsoft.Practices.EnterpriseLibrary.Common.Configuration.ObjectBuilder;

namespace EntLibContrib.Query
{
	/// <summary>
	/// This interface defines the contract that must be implemented by all queries. 
	/// </summary>
	[CustomFactory(typeof(QueryCustomFactory))]
	public interface IQuery
	{
		#region Properties
		/// <summary>
		/// Gets the query name.
		/// </summary>
		/// <value>The name.</value>
		string Name
		{
			get;
		}

		/// <summary>
		/// Gets the custom command.
		/// </summary>
		/// <value>The custom command.</value>
		ICustomCommand CustomCommand
		{
			get;
		}

		/// <summary>
		/// Gets the query parameter set.
		/// </summary>
		/// <value>A set of parameters.</value>
		IParameterSet ParameterSet
		{
			get;
		}

		/// <summary>
		/// Gets or sets the instrumentation provider.
		/// </summary>
		/// <value>The instrumentation provider.</value>
		QueryInstrumentationProvider InstrumentationProvider
		{
			get;
		}
		#endregion

		#region Public Methods
		/// <summary>
		/// Executes a read command and returns the results.
		/// </summary>
		/// <returns>
		/// Dataset containing the results of the read operation
		/// </returns>
		/// <remarks>
		/// 	<para>this method requires the parameter values to be set through the properties.</para>
		/// 	<para>Output parameters will update the parameter property values.</para>
		/// </remarks>
		DataSet ExecuteForRead();

		/// <summary>
		/// Executes a read command and returns the results.
		/// </summary>
		/// <param name="parameterValues">The parameter values.</param>
		/// <returns>
		/// Dataset containing the results of the read operation
		/// </returns>
		/// <remarks>
		/// 	<para>This method takes the parameter values from the given dictionary.</para>
		/// 	<para>Output parameters will update the parameter property values.</para>
		/// </remarks>
		DataSet ExecuteForRead(IDictionary<string, object> parameterValues);

		/// <summary>
		/// Executes a write command and saves data to the data source.
		/// </summary>
		/// <remarks>
		/// 	<para>this method requires the parameter values to be set through the properties.</para>
		/// 	<para>Output parameters will update the parameter property values.</para>
		/// </remarks>
		void ExecuteForWrite();

		/// <summary>
		/// Executes a write command and saves data to the data source.
		/// </summary>
		/// <param name="parameterValues">The parameter values.</param>
		/// <remarks>
		/// 	<para>This method takes the parameter values from the given dictionary.</para>
		/// 	<para>Output parameters will update the parameter property values.</para>
		/// </remarks>
		void ExecuteForWrite(IDictionary<string, object> parameterValues);

		/// <summary>
		/// Executes a write command and saves data to the data source.
		/// </summary>
		/// <param name="parameterValues">The parameter values as a DataSet.</param>
		/// <remarks>
		/// 	<para>This method takes the parameter values from the given dataset.</para>
		/// 	<para>The dataset column names must match the parameter names.</para>
		/// 	<para>Multiple rows in the dataset will result in multiple writes to the data source.</para>
		/// 	<para>Output parameters will update the parameter property values but this only makes sense for single row datasets.</para>
		/// </remarks>
		void ExecuteForWrite(DataSet parameterValues);
		#endregion
	}
}